CNavServices Read Me
Copyright  1998 Dair Grant, <mailto:dair@kagi.com>

What is CNavServices?

CNavServices is a utility class that provides access to Navigation Services for PowerPlant applications. It uses Navigation Services directly if it's available, and the normal Standard File package if not. This allows applications to support Navigation Services under both Mac OS 8 and System 7, without having to write additional code.

CNavServices does not expose the whole of the Navigation Services API, as it offers a wide range of functionality not possible under Standard File. However, it does give you a very quick route to adopting Navigation Services and immediately allows you access to movable, and resizable, file dialogs.

If you have heavily customised your standard file dialogs, CNavServices may not be suitable - you will need to work with Navigation Services directly (since there is no straightforward mapping between a heavily customised Standard File dialog and the customisation mechanism within Navigation Services).

However, if your application simply uses the standard Standard File dialogs, CNavServices will be suitable. Standard File filter callbacks can be used unchanged.


How does it work?

CNavServices provides two static methods, which are called on application initialisation and termination. As well as allowing Navigation Services to be preloaded (so that it loads once at startup, rather than each time a dialog is displayed), your application can also indicate if it will be happy to receive update and idle events while a dialog is displayed.

This is strongly recommended, and CNavServices will automatically dispatch events to the current LEventDispatcher without any further work on your part. This allows Navigation Services to use movable, and resizable, file dialogs.

CNavServices also provides two methods which take the same parameters, and have the same behaviour, as the StandardGetFile and StandardPutFile API calls. These methods call Standard File directly, or use Navigation Services to provide equivalents.

Your application can also indicate that it will accept multiple selections when opening a file. If it does, and only one file is selected, the file will be returned via the StandardFileReply as normal. If multiple files are selected, your application will be sent an appropriate Apple Event (exactly as if the files had been double-clicked in the Finder).



How do I use it?

To use CNavServices within your application, you need to take the following steps:

1. Add CNavServices and the Navigation Services library to your project. You can obtain the Navigation Services library from Apple's developer web site, which is at <http://devworld.apple.com/>. If it's not immediately accessible as a development kit, try using the search field at the bottom of the web page to locate it.

You will probably want to weak link against the Navigation Services library. This will allow your application to launch without it, and CNavServices will fall back to Standard File.


2. Add the following code to your application's constructor:

    #include "CNavServices"
    ...
    CNavServices::InitNavServices(true, true);

This initialises CNavServices, indicates that you want the Navigation Services library to be loaded once at startup, and that your application is happy to receive update and idle events while a dialog is up (which allows Navigation Services to provide a movable modal, and resizable, file dialog).


3. Add the following code to your application's destructor:

    #include "CNavServices"
    ...
    CNavServices::TerminateNavServices();

This terminates CNavServices, unloading the Navigation Services library if it was loaded at startup.


4. Replace calls to Standard File with calls to CNavServices. E.g., code which which looked like:

    StandardGetFile(...);
    ...
    StandardPutFile(...);
 
should be replaced with code which looks like:

    #include "CNavServices"
    ...
    CNavServices navServices;
    ...
    navServices.GetFile(...);
    ...
    navServices.PutFile(...);

Note that you do not need to create a new CNavServices object for each dialog, nor do you need to change the parameters you now pass to Standard File.

CNavServices::GetFile does take one additional parameter, which indicates if you want to allow multiple files to be opened at once. This defaults to false, producing the same behaviour as StandardGetFile.

This is all that needs to be done to enable your application to use Navigation Services. For more advanced functionality (e.g., "do you want to discard changes" dialogs, or advanced translation of files), you should consult the Navigation Services SDK.


Anything else?

If you use CNavServices.cp within a freeware or shareware project, you may do so for free. A credit in your documentation would be nice, but it's not required. If you use CNavServices.cp within a commercial product, you must include a credit within your documentation.

If you find any bugs, or have any suggestions for improvements, please let me know.


-dair
<mailto:dair@kagi.com>
<http://www.kagi.com/dair/purpleshark.html>